Autogenerated HTML docs for v2.15.0-317-g14c63
diff --git a/RelNotes/2.15.1.txt b/RelNotes/2.15.1.txt index 15b24a0..47f23b5 100644 --- a/RelNotes/2.15.1.txt +++ b/RelNotes/2.15.1.txt
@@ -64,5 +64,17 @@ * Updates from GfW project. + * "git rebase -i" recently started misbehaving when a submodule that + is configured with 'submodule.<name>.ignore' is dirty; this has + been corrected. + + * Some error messages did not quote filenames shown in it, which have + been fixed. + + * Building with NO_LIBPCRE1_JIT did not disable it, which has been fixed. + + * We used to add an empty alternate object database to the system + that does not help anything; it has been corrected. + Also contains various documentation updates and code clean-ups.
diff --git a/RelNotes/2.16.0.txt b/RelNotes/2.16.0.txt index 12b86eb..f57acec 100644 --- a/RelNotes/2.16.0.txt +++ b/RelNotes/2.16.0.txt
@@ -63,6 +63,9 @@ HTML version via AsciiDoc/Asciidoctor. (merge 049e64aa50 bc/submitting-patches-in-asciidoc later to maint). + * We learned to talk to watchman to speed up "git status" and other + operations that need to see which paths have been modified. + Performance, Internal Implementation, Development Support etc. @@ -90,18 +93,15 @@ * Conversion from uchar[20] to struct object_id continues. * Code cleanup. - (merge 62a24c8923 rs/hex-to-bytes-cleanup later to maint). * A single-word "unsigned flags" in the diff options is being split into a structure with many bitfields. - (merge 0d1e0e7801 bw/diff-opt-impl-to-bitfields later to maint). * TravisCI build updates. * Parts of a test to drive the long-running content filter interface has been split into its own module, hopefully to eventually become reusable. - (merge 0fe8d516bb cc/git-packet-pm later to maint). * Drop (perhaps overly cautious) sanity check before using the index read from the filesystem at runtime. @@ -187,25 +187,22 @@ * Some error messages did not quote filenames shown in it, which have been fixed. - (merge 0a288d1ee9 sr/wrapper-quote-filenames later to maint). * "git rebase -i" recently started misbehaving when a submodule that is configured with 'submodule.<name>.ignore' is dirty; this has been corrected. - (merge c6d8ccf3a2 bw/rebase-i-ignored-submodule-fix later to maint). * Building with NO_LIBPCRE1_JIT did not disable it, which has been fixed. - (merge 2fff1e196d ab/pcre-v2 later to maint). * We used to add an empty alternate object database to the system that does not help anything; it has been corrected. - (merge f28e36686a jk/info-alternates-fix later to maint). + + * Doc update around use of "format-patch --subject-prefix" etc. + (merge f6be7edcac ad/submitting-patches-title-decoration later to maint). + + * A fix for an ancient bug in "git apply --ignore-space-change" codepath. + (merge 6ce15ce576 rs/apply-fuzzy-match-fix later to maint). * Other minor doc, test and build updates and code cleanups. - (merge 804862209b ao/merge-verbosity-getenv-just-once later to maint). - (merge 9360ec0002 rs/sequencer-rewrite-file-cleanup later to maint). (merge f4e45cb3eb ma/bisect-leakfix later to maint). (merge 4da72644b7 ma/reduce-heads-leakfix later to maint). - (merge 3dc5433fd5 ad/rebase-i-serie-typofix later to maint). - (merge 5313bee032 tz/fsf-address-update later to maint). - (merge 5555a2aa4b cb/t4201-robustify later to maint).
diff --git a/SubmittingPatches.html b/SubmittingPatches.html index 0513ac5..98f605c 100644 --- a/SubmittingPatches.html +++ b/SubmittingPatches.html
@@ -949,20 +949,25 @@ </div> <div class="paragraph"><p>It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other -e-mail discussions. Use of additional markers after PATCH and -the closing bracket to mark the nature of the patch is also -encouraged. E.g. [PATCH/RFC] is often used when the patch is -not ready to be applied but it is for discussion, [PATCH v2], -[PATCH v3] etc. are often seen when you are sending an update to -what you have previously sent.</p></div> -<div class="paragraph"><p><code>git format-patch</code> command follows the best current practice to +e-mail discussions. Use of markers in addition to PATCH within +the brackets to describe the nature of the patch is also +encouraged. E.g. [RFC PATCH] (where RFC stands for "request for +comments") is often used to indicate a patch needs further +discussion before being accepted, [PATCH v2], [PATCH v3] etc. +are often seen when you are sending an update to what you have +previously sent.</p></div> +<div class="paragraph"><p>The <code>git format-patch</code> command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the Signed-off-by: lines, and a line that consists of three dashes, followed by the diffstat information and the patch itself. If you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit -message starts, you can put a "From: " line to name that person.</p></div> +message starts, you can put a "From: " line to name that person. +To change the default "[PATCH]" in the subject to "[<text>]", use +<code>git format-patch --subject-prefix=<text></code>. As a shortcut, you +can use <code>--rfc</code> instead of <code>--subject-prefix="RFC PATCH"</code>, or +<code>-v <n></code> instead of <code>--subject-prefix="PATCH v<n>"</code>.</p></div> <div class="paragraph"><p>You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter" material between the three-dash line and the diffstat. For @@ -1368,7 +1373,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2017-11-15 14:56:54 JST +Last updated 2017-11-21 14:32:28 JST </div> </div> </body>
diff --git a/SubmittingPatches.txt b/SubmittingPatches.txt index 17419f7..3ef3092 100644 --- a/SubmittingPatches.txt +++ b/SubmittingPatches.txt
@@ -203,14 +203,15 @@ It is a common convention to prefix your subject line with [PATCH]. This lets people easily distinguish patches from other -e-mail discussions. Use of additional markers after PATCH and -the closing bracket to mark the nature of the patch is also -encouraged. E.g. [PATCH/RFC] is often used when the patch is -not ready to be applied but it is for discussion, [PATCH v2], -[PATCH v3] etc. are often seen when you are sending an update to -what you have previously sent. +e-mail discussions. Use of markers in addition to PATCH within +the brackets to describe the nature of the patch is also +encouraged. E.g. [RFC PATCH] (where RFC stands for "request for +comments") is often used to indicate a patch needs further +discussion before being accepted, [PATCH v2], [PATCH v3] etc. +are often seen when you are sending an update to what you have +previously sent. -`git format-patch` command follows the best current practice to +The `git format-patch` command follows the best current practice to format the body of an e-mail message. At the beginning of the patch should come your commit message, ending with the Signed-off-by: lines, and a line that consists of three dashes, @@ -218,6 +219,10 @@ you are forwarding a patch from somebody else, optionally, at the beginning of the e-mail message just before the commit message starts, you can put a "From: " line to name that person. +To change the default "[PATCH]" in the subject to "[<text>]", use +`git format-patch --subject-prefix=<text>`. As a shortcut, you +can use `--rfc` instead of `--subject-prefix="RFC PATCH"`, or +`-v <n>` instead of `--subject-prefix="PATCH v<n>"`. You often want to add additional explanation about the patch, other than the commit message itself. Place such "cover letter"
diff --git a/config.txt b/config.txt index 671fcba..5f65fa9 100644 --- a/config.txt +++ b/config.txt
@@ -416,6 +416,13 @@ 8.3 "short" names. Defaults to `true` on Windows, and `false` elsewhere. +core.fsmonitor:: + If set, the value of this variable is used as a command which + will identify all files that may have changed since the + requested date/time. This information is used to speed up git by + avoiding unnecessary processing of files that have not changed. + See the "fsmonitor-watchman" section of linkgit:githooks[5]. + core.trustctime:: If false, the ctime differences between the index and the working tree are ignored; useful when the inode change time
diff --git a/git-config.html b/git-config.html index 3eda8f8..ebf7eee 100644 --- a/git-config.html +++ b/git-config.html
@@ -1956,6 +1956,18 @@ </p> </dd> <dt class="hdlist1"> +core.fsmonitor +</dt> +<dd> +<p> + If set, the value of this variable is used as a command which + will identify all files that may have changed since the + requested date/time. This information is used to speed up git by + avoiding unnecessary processing of files that have not changed. + See the "fsmonitor-watchman" section of <a href="githooks.html">githooks(5)</a>. +</p> +</dd> +<dt class="hdlist1"> core.trustctime </dt> <dd>
diff --git a/git-ls-files.html b/git-ls-files.html index 4cc6fab..806f7ad 100644 --- a/git-ls-files.html +++ b/git-ls-files.html
@@ -748,7 +748,7 @@ <h2 id="_synopsis">SYNOPSIS</h2> <div class="sectionbody"> <div class="verseblock"> -<pre class="content"><em>git ls-files</em> [-z] [-t] [-v] +<pre class="content"><em>git ls-files</em> [-z] [-t] [-v] [-f] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* [--eol] @@ -1041,6 +1041,16 @@ </p> </dd> <dt class="hdlist1"> +-f +</dt> +<dd> +<p> + Similar to <code>-t</code>, but use lowercase letters for files + that are marked as <em>fsmonitor valid</em> (see + <a href="git-update-index.html">git-update-index(1)</a>). +</p> +</dd> +<dt class="hdlist1"> --full-name </dt> <dd> @@ -1200,7 +1210,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2017-04-17 16:27:49 JST +Last updated 2017-11-21 14:32:26 JST </div> </div> </body>
diff --git a/git-ls-files.txt b/git-ls-files.txt index d153c17..3ac3e3a 100644 --- a/git-ls-files.txt +++ b/git-ls-files.txt
@@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] -'git ls-files' [-z] [-t] [-v] +'git ls-files' [-z] [-t] [-v] [-f] (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* (-[c|d|o|i|s|u|k|m])* [--eol] @@ -133,6 +133,11 @@ that are marked as 'assume unchanged' (see linkgit:git-update-index[1]). +-f:: + Similar to `-t`, but use lowercase letters for files + that are marked as 'fsmonitor valid' (see + linkgit:git-update-index[1]). + --full-name:: When run from a subdirectory, the command usually outputs paths relative to the current directory. This
diff --git a/git-update-index.html b/git-update-index.html index 03d6f70..435fc8e 100644 --- a/git-update-index.html +++ b/git-update-index.html
@@ -755,9 +755,11 @@ [--chmod=(+|-)x] [--[no-]assume-unchanged] [--[no-]skip-worktree] + [--[no-]fsmonitor-valid] [--ignore-submodules] [--[no-]split-index] [--[no-|test-|force-]untracked-cache] + [--[no-]fsmonitor] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] @@ -922,6 +924,17 @@ </p> </dd> <dt class="hdlist1"> +--[no-]fsmonitor-valid +</dt> +<dd> +<p> + When one of these flags is specified, the object name recorded + for the paths are not updated. Instead, these options + set and unset the "fsmonitor valid" bit for the paths. See + section "File System Monitor" below for more information. +</p> +</dd> +<dt class="hdlist1"> -g </dt> <dt class="hdlist1"> @@ -1080,6 +1093,22 @@ </p> </dd> <dt class="hdlist1"> +--fsmonitor +</dt> +<dt class="hdlist1"> +--no-fsmonitor +</dt> +<dd> +<p> + Enable or disable files system monitor feature. These options + take effect whatever the value of the <code>core.fsmonitor</code> + configuration variable (see <a href="git-config.html">git-config(1)</a>). But a warning + is emitted when the change goes against the configured value, as + the configured value will take effect next time the index is + read and this will remove the intended effect of the option. +</p> +</dd> +<dt class="hdlist1"> -- </dt> <dd> @@ -1376,6 +1405,31 @@ </div> </div> <div class="sect1"> +<h2 id="_file_system_monitor">File System Monitor</h2> +<div class="sectionbody"> +<div class="paragraph"><p>This feature is intended to speed up git operations for repos that have +large working directories.</p></div> +<div class="paragraph"><p>It enables git to work together with a file system monitor (see the +"fsmonitor-watchman" section of <a href="githooks.html">githooks(5)</a>) that can +inform it as to what files have been modified. This enables git to avoid +having to lstat() every file to find modified files.</p></div> +<div class="paragraph"><p>When used in conjunction with the untracked cache, it can further improve +performance by avoiding the cost of scanning the entire working directory +looking for new files.</p></div> +<div class="paragraph"><p>If you want to enable (or disable) this feature, it is easier to use +the <code>core.fsmonitor</code> configuration variable (see +<a href="git-config.html">git-config(1)</a>) than using the <code>--fsmonitor</code> option to +<code>git update-index</code> in each repository, especially if you want to do so +across all repositories you use, because you can set the configuration +variable to <code>true</code> (or <code>false</code>) in your <code>$HOME/.gitconfig</code> just once +and have it affect all repositories you touch.</p></div> +<div class="paragraph"><p>When the <code>core.fsmonitor</code> configuration variable is changed, the +file system monitor is added to or removed from the index the next time +a command reads the index. When <code>--[no-]fsmonitor</code> are used, the file +system monitor is immediately added to or removed from the index.</p></div> +</div> +</div> +<div class="sect1"> <h2 id="_configuration">Configuration</h2> <div class="sectionbody"> <div class="paragraph"><p>The command honors <code>core.filemode</code> configuration variable. If @@ -1418,7 +1472,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2017-09-25 16:24:34 JST +Last updated 2017-11-21 14:32:26 JST </div> </div> </body>
diff --git a/git-update-index.txt b/git-update-index.txt index 75c7dd9..bdb0342 100644 --- a/git-update-index.txt +++ b/git-update-index.txt
@@ -16,9 +16,11 @@ [--chmod=(+|-)x] [--[no-]assume-unchanged] [--[no-]skip-worktree] + [--[no-]fsmonitor-valid] [--ignore-submodules] [--[no-]split-index] [--[no-|test-|force-]untracked-cache] + [--[no-]fsmonitor] [--really-refresh] [--unresolve] [--again | -g] [--info-only] [--index-info] [-z] [--stdin] [--index-version <n>] @@ -111,6 +113,12 @@ set and unset the "skip-worktree" bit for the paths. See section "Skip-worktree bit" below for more information. +--[no-]fsmonitor-valid:: + When one of these flags is specified, the object name recorded + for the paths are not updated. Instead, these options + set and unset the "fsmonitor valid" bit for the paths. See + section "File System Monitor" below for more information. + -g:: --again:: Runs 'git update-index' itself on the paths whose index @@ -201,6 +209,15 @@ `--untracked-cache` used to imply `--test-untracked-cache` but this option would enable the extension unconditionally. +--fsmonitor:: +--no-fsmonitor:: + Enable or disable files system monitor feature. These options + take effect whatever the value of the `core.fsmonitor` + configuration variable (see linkgit:git-config[1]). But a warning + is emitted when the change goes against the configured value, as + the configured value will take effect next time the index is + read and this will remove the intended effect of the option. + \--:: Do not interpret any more arguments as options. @@ -447,6 +464,34 @@ are used, the untracked cache is immediately added to or removed from the index. +File System Monitor +------------------- + +This feature is intended to speed up git operations for repos that have +large working directories. + +It enables git to work together with a file system monitor (see the +"fsmonitor-watchman" section of linkgit:githooks[5]) that can +inform it as to what files have been modified. This enables git to avoid +having to lstat() every file to find modified files. + +When used in conjunction with the untracked cache, it can further improve +performance by avoiding the cost of scanning the entire working directory +looking for new files. + +If you want to enable (or disable) this feature, it is easier to use +the `core.fsmonitor` configuration variable (see +linkgit:git-config[1]) than using the `--fsmonitor` option to +`git update-index` in each repository, especially if you want to do so +across all repositories you use, because you can set the configuration +variable to `true` (or `false`) in your `$HOME/.gitconfig` just once +and have it affect all repositories you touch. + +When the `core.fsmonitor` configuration variable is changed, the +file system monitor is added to or removed from the index the next time +a command reads the index. When `--[no-]fsmonitor` are used, the file +system monitor is immediately added to or removed from the index. + Configuration -------------
diff --git a/git.html b/git.html index 5bbeb09..cb41855 100644 --- a/git.html +++ b/git.html
@@ -2769,6 +2769,15 @@ "false" (case insensitive) disables trace messages.</p></div> </dd> <dt class="hdlist1"> +<code>GIT_TRACE_FSMONITOR</code> +</dt> +<dd> +<p> + Enables trace messages for the filesystem monitor extension. + See <code>GIT_TRACE</code> for available trace output options. +</p> +</dd> +<dt class="hdlist1"> <code>GIT_TRACE_PACK_ACCESS</code> </dt> <dd> @@ -3095,7 +3104,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2017-11-10 15:00:41 JST +Last updated 2017-11-21 14:32:26 JST </div> </div> </body>
diff --git a/git.txt b/git.txt index 463b0eb..483a1f3 100644 --- a/git.txt +++ b/git.txt
@@ -595,6 +595,10 @@ Unsetting the variable, or setting it to empty, "0" or "false" (case insensitive) disables trace messages. +`GIT_TRACE_FSMONITOR`:: + Enables trace messages for the filesystem monitor extension. + See `GIT_TRACE` for available trace output options. + `GIT_TRACE_PACK_ACCESS`:: Enables trace messages for all accesses to any packs. For each access, the pack file name and an offset in the pack is
diff --git a/githooks.html b/githooks.html index a488a69..58df1a1 100644 --- a/githooks.html +++ b/githooks.html
@@ -1141,6 +1141,29 @@ non-zero status causes <em>git send-email</em> to abort before sending any e-mails.</p></div> </div> +<div class="sect2"> +<h3 id="_fsmonitor_watchman">fsmonitor-watchman</h3> +<div class="paragraph"><p>This hook is invoked when the configuration option core.fsmonitor is +set to .git/hooks/fsmonitor-watchman. It takes two arguments, a version +(currently 1) and the time in elapsed nanoseconds since midnight, +January 1, 1970.</p></div> +<div class="paragraph"><p>The hook should output to stdout the list of all files in the working +directory that may have changed since the requested time. The logic +should be inclusive so that it does not miss any potential changes. +The paths should be relative to the root of the working directory +and be separated by a single NUL.</p></div> +<div class="paragraph"><p>It is OK to include files which have not actually changed. All changes +including newly-created and deleted files should be included. When +files are renamed, both the old and the new name should be included.</p></div> +<div class="paragraph"><p>Git will limit what files it checks for changes as well as which +directories are checked for untracked files based on the path names +given.</p></div> +<div class="paragraph"><p>An optimized way to tell git "all files have changed" is to return +the filename <em>/</em>.</p></div> +<div class="paragraph"><p>The exit status determines whether git will use the data from the +hook to limit its search. On error, it will fall back to verifying +all files and folders.</p></div> +</div> </div> </div> <div class="sect1"> @@ -1153,7 +1176,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2017-09-29 13:22:11 JST +Last updated 2017-11-21 14:32:26 JST </div> </div> </body>
diff --git a/githooks.txt b/githooks.txt index 5d3f455..0bb0042 100644 --- a/githooks.txt +++ b/githooks.txt
@@ -454,6 +454,34 @@ non-zero status causes 'git send-email' to abort before sending any e-mails. +fsmonitor-watchman +~~~~~~~~~~~~~~~~~~ + +This hook is invoked when the configuration option core.fsmonitor is +set to .git/hooks/fsmonitor-watchman. It takes two arguments, a version +(currently 1) and the time in elapsed nanoseconds since midnight, +January 1, 1970. + +The hook should output to stdout the list of all files in the working +directory that may have changed since the requested time. The logic +should be inclusive so that it does not miss any potential changes. +The paths should be relative to the root of the working directory +and be separated by a single NUL. + +It is OK to include files which have not actually changed. All changes +including newly-created and deleted files should be included. When +files are renamed, both the old and the new name should be included. + +Git will limit what files it checks for changes as well as which +directories are checked for untracked files based on the path names +given. + +An optimized way to tell git "all files have changed" is to return +the filename '/'. + +The exit status determines whether git will use the data from the +hook to limit its search. On error, it will fall back to verifying +all files and folders. GIT ---
diff --git a/technical/index-format.html b/technical/index-format.html index 6f5114b..1749d2a 100644 --- a/technical/index-format.html +++ b/technical/index-format.html
@@ -1274,11 +1274,51 @@ </ul></div> </div> </div> +<div class="sect1"> +<h2 id="_file_system_monitor_cache">File System Monitor cache</h2> +<div class="sectionbody"> +<div class="literalblock"> +<div class="content"> +<pre><code>The file system monitor cache tracks files for which the core.fsmonitor +hook has told us about changes. The signature for this extension is +{ 'F', 'S', 'M', 'N' }.</code></pre> +</div></div> +<div class="literalblock"> +<div class="content"> +<pre><code>The extension starts with</code></pre> +</div></div> +<div class="ulist"><ul> +<li> +<p> +32-bit version number: the current supported version is 1. +</p> +</li> +<li> +<p> +64-bit time: the extension data reflects all changes through the given + time which is stored as the nanoseconds elapsed since midnight, + January 1, 1970. +</p> +</li> +<li> +<p> +32-bit bitmap size: the size of the CE_FSMONITOR_VALID bitmap. +</p> +</li> +<li> +<p> +An ewah bitmap, the n-th bit indicates whether the n-th index entry + is not CE_FSMONITOR_VALID. +</p> +</li> +</ul></div> +</div> +</div> </div> <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2015-10-30 06:44:28 JST +Last updated 2017-11-21 14:32:26 JST </div> </div> </body> diff --git a/technical/index-format.txt b/technical/index-format.txt index ade0b0c..db35726 100644 --- a/technical/index-format.txt +++ b/technical/index-format.txt
@@ -295,3 +295,22 @@ in the previous ewah bitmap. - One NUL. + +== File System Monitor cache + + The file system monitor cache tracks files for which the core.fsmonitor + hook has told us about changes. The signature for this extension is + { 'F', 'S', 'M', 'N' }. + + The extension starts with + + - 32-bit version number: the current supported version is 1. + + - 64-bit time: the extension data reflects all changes through the given + time which is stored as the nanoseconds elapsed since midnight, + January 1, 1970. + + - 32-bit bitmap size: the size of the CE_FSMONITOR_VALID bitmap. + + - An ewah bitmap, the n-th bit indicates whether the n-th index entry + is not CE_FSMONITOR_VALID. 